package org.windowkit.toolkit.widget;

import javax.swing.JPanel;


/**
 * Complex Components are panels that contain multiple components
 * and offer some sort of control for them.
 * They are meant to be usefull for writing plugable components
 * that can be reused in the application.
 * Good examples of this are ellipse fields that launch windows
 * and listen for the search results, and often times store
 * data behind the scenes.
 * <p>
 * One important thing to remember when writing a ComplexComponent is
 * that you must override setIdentifier(String) to manually identify
 * all of you contained SComponents.
 * Like so:
 * void setIdentifier(String s){
 *      comp1.setIdentifier(s + ".comp1");
 *      comp2.setIdentifier(s + ".comp2));
 *      etc...
 * }
 *
 * This way all the components will be uniquely identified even if the
 * ComplexComponent is used more then once in a single view.
 * <p>
 * Another important feature of a ComplexComponent is its methods
 * getGridHeight() and getGridWidth().  These represent the gridHeight and gridWidth
 * of the panel if it were to be layed out in a grid bag.
 * LayoutUtils.insertIntoGrid(ComplexComponent) and GridGenerator make
 * use of these fields to insert a component into a panel that is layed out using a
 * gridbag and has the open space to insert the component.
 * So when you write a ComplexComponent you must implement these methods
 * with the appropriate grid width and grid height.
 * Also you should put all your layout code in layoutComponents so if someone
 * wants to use your component but lay it out a little differently they just
 * need to override that method.
 *
 *
 * <p>
 * <table border>
 * <tr><th colspan = 3>History</th></tr>
 * <tr>
 * <th>Date</th><th>Developer</th><th>Description</th>
 * </tr>
 * <tr>
 * <td>9/21/06</td>
 * <td>Rich O'Connell</td>
 * <td>Made setIdentifier(String) abstract. Also added abstract getGridHeight() and
 * getGridWidth() to force these values to be set.</td>
 * </tr>
 * </table>
 *
 * @author Rich O'Connell
 *
 */
public abstract class ComplexComponent extends JPanel {



    /**
	 *
	 */
	private static final long serialVersionUID = 4268019970155574890L;

	public ComplexComponent(){

//        initComponents();
//        layoutComponents();

    }

    /**
     * Override this with the code to layout your panel.
     * This is here only to suggest a uniform place to put layout code.
     * This way if you want to use a complex component but lay it out
     * differently you just need to extend it and override this method.
     */
    abstract protected void layoutComponents();

    /**
     * Override this with the code to initialize your components.
     *
     */
//    abstract protected void initComponents();






    /**
     * You must override this and identify all the
     * components that make up this ComplexComponent
     * as "identifier.`component name`".  If we had this
     * component Identify itslef using its cannonical name
     * then if this component was used twice in the same
     * view we wouldnt have unique names.
     */
    abstract public void setIdentifier(String s);


    /**
     * Return the amount of grid cells needed by this
     * component for its height.
     *
     * @return Returns the gridHeight.
     */
    abstract public int getGridHeight();

    /**
     * Return the number of grid cells needed by this
     * component for its width.
     *
     * @return Returns the gridWidth.
     */
    abstract public int getGridWidth();

}
